Widget API#

The Widget class provides static methods and properties to interact with home screen widgets created using the Scripting app. This API enables rendering widgets, handling configuration parameters, previewing widget layouts, and managing widget timelines.

Class: Widget#

This class cannot be instantiated. All its members are static.

Properties#

Widget.family: WidgetFamily#

Returns the widget family configured by the user. The WidgetFamily determines the size and layout constraints of the widget. Common values include:

• "systemSmall" – small widget
• "systemMedium" – medium widget
• "systemLarge" – large widget
• "accessoryRectangular" – Lock Screen rectangular widget
• "accessoryCircular" – Lock Screen circular widget

Type: WidgetFamily

Widget.displaySize: WidgetDisplaySize#

Returns the widget’s display size in points (width and height), depending on its family and the device's screen.

Type: { width: number; height: number }

Widget.parameter: string#

Returns the value of the parameter configured in the widget’s settings when the script is executed via a home screen widget tap. This is useful for customizing widget content dynamically based on user-defined input.

Type: string

Methods#

Widget.present(element: VirtualNode, reloadPolicy?: WidgetReloadPolicy): void#

Renders the widget UI using a React-like virtual node (JSX.Element). You can optionally specify a reload policy to instruct the system when to request an updated timeline.

Parameters#

• element (VirtualNode) – A JSX element representing the widget UI tree.
• reloadPolicy (WidgetReloadPolicy, optional) – Specifies when WidgetKit should request a new timeline. Defaults to atEnd.

Example#

1function WidgetView() {
2  return <VStack>
3    <Image
4      systemName="globe"
5      resizable
6      scaleToFit
7      frame={{
8        width: 28,
9        height: 28
10      }}
11    />
12    <Text>Hello Scripting!</Text>
13  </VStack>
14}
15
16Widget.present(<WidgetView />, {
17  policy: "after",
18  date: new Date(Date.now() + 1000 * 60 * 5) // 5 minutes later
19})

Returns: void

Widget.preview(options?: PreviewOptions): Promise<void>#

Previews the widget with the specified configuration. This method is available only in index.tsx, not in widget.tsx or intent.tsx.

Parameters#

• options (optional) – Configuration for previewing the widget.

1interface PreviewOptions {
2  family?: WidgetFamily
3  parameters?: {
4    options: Record<string, string> // Map of parameter names to JSON stringified values
5    default: string                 // The default parameter key to use
6  }
7}

Example#

1const options = {
2  "Param 1": JSON.stringify({ color: "red" }),
3  "Param 2": JSON.stringify({ color: "blue" }),
4}
5
6await Widget.preview({
7  family: "systemSmall",
8  parameters: {
9    options,
10    default: "Param 1"
11  }
12})
13console.log("Widget preview dismissed")

Returns: Promise<void> Throws an error if parameters are not formatted correctly.

Widget.reloadAll(): void#

Requests WidgetKit to reload the timelines for all widgets created using the Scripting app. This is useful when the data or appearance of widgets may have changed and needs to be refreshed.

Returns: void

Related Types#

WidgetFamily#

A string enum representing available widget sizes. Typical values:

1type WidgetFamily =
2  | "systemSmall"
3  | "systemMedium"
4  | "systemLarge"
5  | "accessoryCircular"
6  | "accessoryRectangular"

WidgetDisplaySize#

An object representing the widget’s current width and height in points:

1interface WidgetDisplaySize {
2  width: number
3  height: number
4}

WidgetReloadPolicy#

An object specifying when WidgetKit should request a new timeline:

1type WidgetReloadPolicy =
2  | { policy: "atEnd" } // Reload after the timeline ends (default)
3  | { policy: "after", date: Date } // Reload after a specific date

Usage Notes#

• Widget.present should be used inside widget.tsx to define and display the actual widget content.
• Widget.preview is a development utility used in index.tsx to simulate how widgets look and behave with different parameters.
• You must call Script.exit() at the end of the widget script to ensure proper lifecycle handling.
• When using parameters, remember to parse Widget.parameter as JSON if it contains structured data.